Mac Format 1996 April/MacFormat CD Edition MF36 (April 1996).iso/Shareware City/Developers/Tools Plus - GUI⁄Event libs/Tools Plus 2.6.1a Evaluat'n Kit/Tools Plus 2.6.1a/User Manual/05-Windows (1 of 3)

INI File | 1994-09-17 | 30KB | 366 lines

[Display using Monaco 9]


5  Windows
``````````

  Windows opened by Tools Plus are identical to those opened by conventional Macintosh toolbox routines, except that they and the objects on them inherit the benefit of being automatically maintained by Tools Plus.  Some additional features can also be found in Tools Plus windows that aren’t available in ordinary Macintosh windows.  Tools Plus also supports the following window types:
    • All 6 standard Macintosh window types
    • Tool Bar
    • Floating Palettes (with thin title bar at the top of the window)
    • Floating Palettes (with drag bar on left side of window)

  Before you can use a window, you must first open it with the WindowOpen procedure.  Each window is referenced by a unique window number.  This number is specified when the window is opened, and refers to the specific window until that window is closed.  After a window has been opened, your application can create objects in it, such as buttons, lists, scroll bars, editing fields, etc.  These items are detailed later in this manual.

  Your application can also have a tool bar located just below the menu bar.  It is created with the ToolBarOpen procedure.  From a programming perspective, a tool bar is treated just like any other window.

  At any time, your application can obtain information about a window’s location, size, and status with the WindowStatus routine.

  Routines that should be used infrequently include WindowMove which lets your application reposition a window, WindowSize which lets your application resize a window, and WindowDisplay which is used to hide and show (unhide) a window.  In all cases, Tools Plus correctly maintains your application’s user interface to accommodate the changes brought about by these routines.

  You can use Tools Plus’s windows instead of creating alerts and dialogs with ResEdit.  Tools Plus can provide all the functionality that real alerts and dialogs can, plus it provides additional benefits such as letting you easily incorporate pop-up menus, list boxes, and alternate fonts.  See the section on Dynamic Alerts for details on Tools Plus alerts.

  When a window is no longer required, it is closed by the WindowClose procedure, which releases the memory used by the window’s buttons (including radio buttons and check boxes), picture buttons, scroll bars, editing fields, pop-up menus, list boxes, and custom controls.

Note: Much of the Macintosh’s power lies in QuickDraw, the part of the
      toolbox that allows Macintosh programmers to perform highly
      complex graphic operations quickly and easily.  There is an entire
      chapter in Volume I of Inside Macintosh dedicated to QuickDraw
      that is compulsory reading for all Macintosh programmers.  The
      chapter on the Font Manager (Inside Macintosh Volume I) explains
      how to display text on a window.





Title Bar, Close box, and Zoom box
``````````````````````````````````
  Any window that contains a title bar can have a “close box.” Also, a document window type can be resized by the user by either clicking on the “zoom box” or dragging the “size box.”  The close box, when clicked by the user, instructs your application to close the window.

  A window containing a zoom box (the box in the right side of the title bar) has two different states: [1] the standard state, and [2] the user state.  The user can change the window’s size and/or location, thereby defining the user state.  When the zoom box is clicked, the window automatically “zooms” back to the standard state (which can be defined by your application).  Clicking the zoom box again reverts to the user state.  (Floating palettes can’t have a zoom box).

  Your application can define the minimum and maximum size of a window with SetWindowSizeLimits.  It can also define the size and position the window will assume when the zoom box is clicked by using the SetWindowZoom procedure.  GetWindowZoom is used to retrieve the window’s current size and location, as well as the size and location that is assumed when the zoom box is clicked.

  Any window with a title bar can be re-positioned by dragging it with the mouse.  An inactive window can be dragged without being activated by holding the Command key down during the drag.  A window’s title can be changed by the WindowTitle procedure.





Size Box
````````
  A size box is a square located in the bottom right corner of a sizable document window.  The user can change a window’s size by dragging the size box.  By default, the window can be sized horizontally to any width from a minimum 120 pixels to the full width of the screen.  Vertically, the window can be sized to any height from a minimum of 68 pixels to the full height of the screen (excluding the height of the menu bar).  When the window is opened, the default sizing limits for the window are automatically adjusted to the window’s size.  For example, the minimum size will never be larger than the window’s dimensions, and the maximum size will never be smaller than the window’s dimensions.  These sizing limits can be changed by the SetWindowSizeLimits procedure.





Maximum Number of Open Windows
``````````````````````````````
  The maximum number of windows that can be opened simultaneously is dictated by the InitToolsPlus procedure.  Note that each potential window consumes some memory even if it is never used during the course of your application.





Tool Bar and Floating Palettes
``````````````````````````````
  From a programming perspective, the tool bar and floating palettes are just another kind of window.  The tool bar is created with the ToolBarOpen procedure, whereas floating palettes are opened with the WindowOpen procedure (just like ordinary windows).  Tools Plus takes care of making them behave properly by ensuring that they are always active, and that they stay in front of standard windows.

  The tool bar and all open floating palettes in your application are active as long as your application is active (when it is suspended under MultiFinder or System 7, the tool bar and floating palettes are automatically hidden).  The user can make use of the controls located in the tool bar and floating palettes at any time.  The actions invoked by those controls usually apply to the front most window that is not a tool bar or floating palette.

  Your application can determine the front most floating palette with the FirstPaletteNumber routine.

  Even though Tools Plus makes it easy to add a tool bar and floating palettes to your application, you should be aware of what Tools Plus does to make them work.  This information is detailed in this chapter.





Standard Windows
````````````````
  In Tools Plus, a standard window is any window in your application that is not a tool bar or floating palette.  If your application does not use a tool bar or floating palettes, then all your windows are standard windows.  Your application can determine the front most standard window by using the FirstStdWindowNumber routine.





Active Window
`````````````
  The active window is the window that is acted upon whenever the user types, gives commands, or does whatever is appropriate within the application being used.  Almost inevitably, this is your application’s front most window when your application is active (i.e., when it is not suspended under MultiFinder or System 7).  Note that the active window may be a desk accessory when running Finder under System 5 or 6.  Since desk accessories are handled automatically by Tools Plus, you only need to be concerned about your own windows.

  In Macintosh toolbox terms, the active window is represented by the global WindowPtr constant FrontWindow.  Although this information is explained in detail in Inside Macintosh I, the basic rule is only one window is active, and it’s the front most one.  Your application can activate a window by using ActivateWindow, and it can determine the active window’s number by using the ActiveWindowNumber function.

  The use of a tool bar or floating palettes introduces additional considerations because your application can now have multiple active windows (explained in the Window Layers model later in this chapter).  The front most “standard” window (not a tool bar or floating palette) still remains the only active standard window.  Additionally, the tool bar and all floating palettes are also active.

  Activating the toolbar has no effect on the front most standard window or any of the floating palettes.  Activating a floating palette simply brings it to the front of other floating palettes, without deactivating any windows.  Activating an inactive standard window deactivates the front most standard window, and brings the newly activated standard window to the front of the standard windows.

  Tools Plus automatically maintains the relationship between standard windows, the tool bar, and floating palette, and makes sure windows are activated and deactivated appropriately.





Work Window
```````````
  With the introduction of the tool bar and floating palettes, your application can simultaneously have multiple active windows (the tool bar, all open floating palettes, and the front most standard window).  This brings up the question: in which window is the user working at the moment?  The concept of a work window is established solely to answer that question.  Tools Plus automatically keeps track of the window that has most recently been the target of user activity.

  Your application has only one work window, which can be determined by using the WorkWindowNumber routine.  A window gains the “work window” status under any of the following conditions:

   • the user clicks in a window, or any object in a window

   • a window is opened as modal (because the next action must take
     place within that window)

   • a standard window is opened (and therefore activated), and the
     previous work window was an active standard window

   • the work window is closed or hidden, in which case the following
     window will become the work window:
        front most standard window (if any are open), or
        front most floating palette (if any are open), or
        the tool bar (if it is open)

   • a window is activated

  If your application does not use a tool bar or floating palettes, the work window is the same as the active window, and you only need to concern yourself with the concepts of an active window and a current window.





Current Window
``````````````
  The current window is the target of actions that occur within your application such as creating buttons or editing fields.  Usually, the current window is the same as the active window, however there are times when it is desirable to affect a window without activating it.  An example of this is when a window needs to be refreshed.  This occurs when a window is obscured by another object on the screen.  When the window is no longer obscured, the newly revealed section must be re-drawn or “refreshed.”

  The CurrentWindow procedure can be used to make any of your application’s windows the “current” window.  When work on the window is completed, it’s good form to make the active window (or work window in the case where a tool bar and/or floating palettes are used) current.  This is done with the CurrentWindowReset procedure.  Your application can also determine the current window’s number by using CurrentWindowNumber.  In Macintosh toolbox terms, the current window’s WindowPtr is represented by the global variable thePort, which is the current grafPort, and can be determined with the GetPort routine.





Editing Field Window
````````````````````
  The Editing Field Window is the one window in your application containing the active editing field (the field either has a flashing insertion point, or its selected text is highlighted).  Tools Plus automatically keeps track of which window contains your application’s active editing field.

  If your application does not use a tool bar or floating palettes, this window will likely be the active window (if it has an editing field).  If your application uses a tool bar and/or floating palettes, potentially any active window (tool bar, any floating palette, or the active standard window) can contain the active editing field.  See the Editing Fields chapter for details on editing fields and the Editing Field Window.





Modal Windows
`````````````
  When a window is modal, clicking the mouse outside the window results in a beep.  This means that all interaction is restricted to the modal window until that window is closed.  Pull-down menus can’t be selected, nor can their Command-key equivalents.  Modal windows are always opened in front of all other windows (including the tool bar and floating palettes).

  When using MultiFinder or System 7, modal windows behave differently: they can be modal for the current application, or for all applications.  The standard dialog box (of dBoxProc type) keeps you in the current application by preventing you from switching to the Finder or other applications, or by launching a new application.  All other modal windows, however, allow you to switch to the Finder or other applications (by clicking on one of their objects), and to launch a new application (by double-clicking it or one of its files).  They do not, however, let you select menu items or click other windows within the same application.  This is consistent with System 7’s movable modal dialog that is displayed while copying a file.

  Your application’s tool bar cannot be modal, nor can any of the floating palettes.





Window Layers
`````````````
  Normally, the Macintosh’s Window Manager maintains your application’s windows in such a way that the front most window is active when your application is active.  When your application is suspended (under MultiFinder or System 7), all windows are inactive.  Tools Plus preserves the Window Manager’s handling of windows (providing your application does not have a tool bar or floating palettes).  When a tool bar or floating palette is introduced in your application, Tools Plus automatically ensures that all windows behave as described in the model below.

  In System 5 and 6’s Finder, only one application can be running at a time.  Additionally, desk accessories can be running, and their windows can intermingle with your application’s windows.  If your application has a tool bar and/or floating palettes, Tools Plus automatically creates a “Desk Accessory Layer” in which all desk accessory windows are kept together to prevent their intermingling with your application’s windows.  This is done to prevent the confusing condition that arises when the front most window is a floating palette or tool bar (belonging to your application), behind which is a desk accessory, followed by another window belonging to your application.  To the user, it may (erroneously) appear that the palette’s operations apply to the desk accessory.

  The following model describes how Tools Plus maintains the order of windows:
                                  Front
                            (Nearest to User)
+---------------+------------------------------------------------------+
| Modal Windows | • Modal windows open at the front of this layer      |
|               | • Multiple modal windows can be open simultaneously  |
|               | • Front most modal window is only accessible window  |
|               |   overriding all others                              |
+---------------+------------------------------------------------------+
| Tool Bar      | • Always active (only one tool bar can be open)      |
|               | • Inaccessible if a modal window is open             |
|               | • Automatically hidden when your application is      |
|               |   suspended                                          |
+---------------+------------------------------------------------------+
| Floating      | • Floating palettes open at the front of this layer  |
| Palettes      | • Always active                                      |
|               | • Multiple floating palettes can be open             |
|               |   simultaneously                                     |
|               | • Inaccessible if a modal window is open             |
|               | • Automatically hidden when your application is      |
|               |   suspended                                          |
+---------------+------------------------------------------------------+
| Standard      | • Standard (modeless, non-tool bar, non-floating     |
| Windows       |   palette) windows open at the front of this  layer  |
|               | • Only the front most window in this layer is active |
|               | • Multiple standard windows can be open              |
|               |   simultaneously                                     |
|               | • When running under System 5 or 6’s Finder, desk    |
|               |   accessory windows may appear in this layer,        |
|               |   providing a tool bar or floating palette is not    |
|               |   open                                               |
|               | • Inaccessible if a modal window is open             |
+---------------+------------------------------------------------------+
                               Window Layer Model




Global and Local Co-ordinates
`````````````````````````````
  There are two co-ordinate systems that are used when creating Tools Plus user interface elements: global and local.  Global co-ordinates are relative to the main monitor where the upper left corner is point 0,0.  Local co-ordinates are relative to the current window where the window’s upper left corner is point 0,0.  The co-ordinate numbers increase when moving right or down, and decrease when moving left or up.

  The Macintosh toolbox has a global variable called screenBits.bounds that is a rectangle defining the boundary of the Macintosh’s main monitor in global co-ordinates.  You may want to use this variable to help you define a window’s maximum size, and zooming co-ordinates.

  Details regarding global and local co-ordinates and screenBits.bounds can be found in Inside Macintosh Volume I.





Handling Windows
````````````````
  Much of the control exercised over windows is performed by your application.  The PollSystem routine is used to constantly inquire about any requests the system may have.  Some of these requests must be acted upon, such as refreshing a window.  Other requests may be interpreted by your application, such as the user clicking in a window’s close box, or clicking in another window.  These facets are all detailed by PollSystem.  Tools Plus automatically handles such chores as sizing, dragging, and zooming windows.

  When working with windows, it is important to remember that many Tools Plus routines (such as creating buttons and editing fields) apply to the current window.

  The Macintosh toolbox’s FrontWindow routine becomes less useful now that the front most window can be a tool bar or any of the floating palettes (instead of the front most standard window).  Fortunately, Tools Plus provides routines to determine the front most floating palette, and front most standard window.

  If your application is drawing in color, see the “Color Drawing & Multiple Monitors” section later in this manual.

------------------------------------------------------------------------

WindowOpen
``````````
Open a new window and make it the “active” and “current” window.

   pascal void WindowOpen (short Window, short left, short top,
                 short right, short bottom,
                 Str255 Title, long procID, Boolean goAwayFlag,
                 Boolean modalFlag);

   procedure WindowOpen(Window, left, top, right, bottom: INTEGER;
                 Title: String; procID: LONGINT; goAwayFlag,
                 modalFlag: BOOLEAN);

  Windows are opened as per the Window Layer model described earlier in this chapter.  To summarize:
    • a modal window opens in front of all other windows, as is the sole
      active window
    • a floating palette opens in front of the floating palette layer,
      and is active
    • a standard window opens in front of the standard window layer, and
      is active if a modal window is not open

  Window specifies the window number that is opened.  Once a window is opened, it is referenced by this window number.  If a window using the same window number is already open, it is closed, then a new window is opened as specified by the parameters in the WindowOpen procedure, thereby re-using the window number.  The newly opened window becomes “active” (front most and highlighted as such) and “current” (action pertaining to graphics, text, buttons, scroll bars, etc. occurs in this window).  Tools Plus allows up to 50 windows to be open simultaneously, however, you may choose to reduce this limit when using InitToolsPlus to initialize Tools Plus.

  Left, top, right, and bottom define a rectangle in global co-ordinates that specifies the window’s size and location.  These parameters can be seen as two corners; the upper left-hand corner (left,top) and the bottom right-hand corner (right,bottom).  Some useful things to remember about sizing your window are:

• The co-ordinates you specify define the usable area.  The window’s
  title bar, outline and shadow are drawn outside these co-ordinates.

• If a document window has a right and/or bottom scroll bar
  (documentProc type), 15 pixels of the usable area are used up by
  the width of the scroll bar.

• Windows with a title bar will use an additional 19 pixels above the
  window’s top co-ordinate to draw the title bar.

• The menu bar takes up 20 pixels, so no window should have a top co-
  ordinate which is less than 20.

If the tool bar is open, and it was created with the tbOffsetNewWindows option, this window’s co-ordinates are shifted downwards by an amount that is equal to the tool bar’s height.


  The Title parameter is the window’s title.  Note that some windows do not have a title.  In this case, the title parameter may be passed as a null string (‘’).

  ProcID is the window definition ID, which specifies a window’s appearance and implies certain behavior.  A documentProc, for instance, is sizable whereas an rDocProc is used for “desk accessory like” windows.  Below are the six (6) standard window definitions.

   documentProc     Standard, sizable document window (has a grow box)
   noGrowDocProc    Standard document window that can’t be re-sized
   rDocProc         Rounded-corner window, like the calculator
   dBoxProc         Standard dialog window (with border, modal)
   plainDBox        Plain dialog box with no border
   altDBoxProc      Plain dialog box with a drop-shadow

  DocumentProc is a standard document window with a grow box (note that unlike ordinary Macintosh windows, the vertical and horizontal lines extending from the grow box are not drawn).  NoGrowDocProc is exactly the same except it does not contain a grow box.  The dBoxProc, plainDBox and altDBoxProc IDs resemble alert or dialog boxes.  They cannot contain a title or size box.  The rDocProc window is used primarily for desk accessories.  It contains no size box.  To include a “zoom box” in either the documentProc or noGrowDocProc type windows, add the constant ZoomBox to the value of the ProcID (i.e. documentProc + ZoomBox).  Floating palettes cannot have a zoom box.

  Additionally, your application can have floating palettes that are always active and “float” above your application’s standard windows.  These types of windows require that a special window definition (WDEF resource) be included in your application’s resource file (see the note at the end of this routine regarding floating palettes).  PaletteProc is used to create a floating palette with a thin title bar across the top of the palette.  AltPaletteProc is used to create an alternate palette that has a drag bar along the left edge of the palette instead of a title bar.  It is possible to create a window that looks like a floating palette but works like a standard window (i.e., it does not always float above the standard window layer) by using the ordPaletteProc ProcID.  If your application uses ordPaletteProc windows, do not use any paletteProc or altPaletteProc windows, because it will be confusing to the user.

  In Tools Plus, you can make any window behave like a floating palette simply by adding the wPalette constant to the window’s procID (both paletteProc and altPaletteProc already include this option).  This allows you to use third-party WDEFs for their appearance, while Tools Plus makes them behave like floating palettes.

   paletteProc      Floating palette with title bar on top
   altPaletteProc   Floating palette with drag bar along left side
   ordPaletteProc   Window that _looks_ like a floating pallete (thin
                    title bar along the top of the window) but _acts_
                    like a standard window.

  You can optionally have Tools Plus position your window for you. The most common example of this is centering a modal dialog on the main monitor (perhaps to display a progress thermometer).  You can also “tile” windows when you need to open multiple windows and you don’t want to calculate each window’s position.  Window tiling calculates the new window’s position relative to the front most standard window (it is not useful for floating palettes or modal windows).  To center or tile a window, add the wCenter or wTile constant to the window’s procID.

  The goAwayFlag indicates if a “close box” is available in the window’s title bar.  Close boxes are only drawn in the documentProc, noGrowDocProc, rDocProc, paletteProc, altPaletteProc, and ordPaletteProc windows.  The two constants that can be used for this flag are GoAway and NoGoAway.

  The modalFlag indicates if the window is “modal” or not.  When a modal window is open, clicking outside the window results in a beep.  This means that all interaction is restricted to the modal window until that window is closed.  The two constants that can be used for this flag are Modal and notModal.  Floating palettes cannot be modal.



Floating Palettes
`````````````````
  If your application uses floating palettes, you will need to include a special window definition (WDEF resource) in your application’s resource fork.  Tools Plus provides the required WDEF, and you can find it in the “Palette WDEF” file in the “Optional Resources” folder on the Tools Plus disk.  Add this WDEF resource to your project’s resource file before you compile your application.

  You can write your own WDEF for floating palettes, or you can use third-party WDEFs.  As per Macintosh standards, a window’s procID is comprised from the following formula: WDEF ID x 16 + variant code.  When you add the wPalette constant to the window’s procID, Tools Plus makes the window behave like a floating palette.


Also see:  ToolBarOpen and WindowOpenRect.


  CONST                        {Window definition IDs:                 }
    documentProc  =     0;     {Standard document window with size box }
    dBoxProc      =     1;     {Alert box or modal dialogue box        }
    plainDBox     =     2;     {Plain box (usually modal)              }
    altDBoxProc   =     3;     {Plain box with shadow (usually modal)  }
    noGrowDocProc =     4;     {Document window without size box       }
    rDocProc      =    16;     {Round corner window (desk accessories) }
    ZoomBox       =     8;     {zoom box (add to procID)               }
    wCenter       = $00010000; {auto-centering (add to procID)         }
    wTile         = $00020000; {auto-tiling (add to procID)            }
    wPalette      = $80000000; {window behaves like palette (to procID)}
    ordPaletteProc= 32000;     {window that looks like Palette         }
    paletteProc   = 32000+wPalette; {T+’s Floating Palette window      }
    altPaletteProc= 32002+wPalette; {T+’s palette with drag bar on left}
                               {“Close box availability” indicators:   }
    goAway        =true;       {Create “close” box                     }
    noGoAway      =false;      {Do not create “close” box              }

                               {“Modal window” indicators:             }
    Modal         =true;       {Window is modal                        }
    notModal      =false;      {Window is modeless                     }


Warning: When you open a window, make sure that the co-ordinates are
         such that at least part of the window’s title bar is visible to
         let the user reposition the window.  If you are using a tool
         bar, make sure you open your window lower to ensure that its
         title bar is not hidden by the tool bar

Note: Although it is programatically possible, you should not open or
      close other windows when a modal window is active.  The only
      exception to this is the use of another modal window as an “Alert”
      message.

------------------------------------------------------------------------

WindowOpenRect
``````````````
Open a new window and make it the “active” and “current” window.

   pascal void WindowOpenRect (short Window, Rect *Bounds,
                 Str255 Title, long procID,
                 Boolean goAwayFlag, Boolean modalFlag);

   procedure WindowOpenRect(Window: INTEGER; Bounds: RECT;
                 Title: String; procID: LONGINT;
                 goAwayFlag, modalFlag: BOOLEAN);

  WindowOpenRect is identical to the WindowOpen procedure, except that it accepts the Bounds rectangle in place of the individual left, top, right and bottom co-ordinates.

------------------------------------------------------------------------